Open textbooks with Quarto and GitHub

Workshop for Education Support colleagues at the UU library

RDM Support

Content

  • Introducing R, RStudio, and Quarto
  • Basic set-up and GitHub publication of a Quarto book
  • ☕ BREAK
  • Text editing in Markdown
  • The git workflow
  • ☕ BREAK
  • Interactivity options (demo)
  • Publishing and archiving

R, RStudio and Quarto

R and RStudio

R logo

Programming language

RStudio logo

Pretty interface to interact with R
(and git, and Quarto)

The Rstudio interface

Quarto

“An open-source scientific and technical publishing system”

  • Turn text documents (.qmd) into html, pdf, epub, docx and more.

    Today: 💻 html (documents that can be hosted on the web)

  • Books 📖, but also: slides, blogs, articles, websites, and more.

Quarto: some history

  • Quarto = more extensive version of R markdown.

  • Rmarkdown: make science more reproducible.

  • Document (.Rmd) containing both R code (R) and text (markdown).

  • When rendering an R markdown document, all code gets executed as well.

  • Same for Quarto!

    But: more features + more recent than R markdown

Basic set-up of a book

💪 Let’s get to work!

Follow the steps here:

https://utrechtuniversity.github.io/open-textbooks/get-started.html

What did we just do?

Dora the explorer

KIOfficialArt, CC BY SA 3.0

  1. Create a Quarto Book project in RStudio

  2. Render the Book to html

  3. Turn the project folder into a git repository (more later!)

  4. Upload (“push”) the project files to GitHub

  5. Turn on GitHub pages to publish the html files online

EX: Make a change and publish it

For example:

  • Open the _quarto.yml file and change the title or authors

  • Change or remove some text from one of the chapters

Remember, to upload a change to GitHub:

  1. git add yourfilewithchanges (select which files to make a snapshot of)
  2. git commit -m "Make x change" (create the snapshot with message)
  3. git push (upload to GitHub)

☕ BREAK 1

Markdown and git

Markdown

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. - Markdown Guide

  • Agnostic way of formatting text.
  • Can be automatically converted to specific outputs, such as html, pdf, etc.
  • Type literally, or use Visual Editor mode!

A few examples

Markdown Syntax Output 
*italics* and **bold**
 italics and bold 
superscript^2^ / subscript~2~
 superscript2 / subscript2 
`verbatim code`
 verbatim code 
# First-level header

First-level header

 
## Second-level header

Second-level header

EX: Markdown tutorial

Do the first 3 exercises of the Markdown tutorial on
https://www.markdowntutorial.com/
(italics/bold, headers, hyperlinks)

Embed multimedia

Embed an image: 
![penguins](https://allisonhorst.github.io/palmerpenguins/reference/figures/lter_penguins.png)

Embed an image:
penguins

Embed a video in Quarto:
{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}

See also Quarto documentation for videos

Embed a video in Quarto:

EX: Embed an image or video

Find an image or video and embed it in one of the chapters of your book! 📖

Git and GitHub

Git logo

  • Version control software
  • Versions of a file are stored as “commits” that can be reverted
  • Not necessarily online, can be on your personal laptop

GitHub logo

  • Website to store git-tracked files
  • Collaborate on files and make suggestions for improvement
  • Also allows hosting html files online (GitHub Pages)

Git workflow (in your terminal)

  1. Pull: Get latest changes from GitHub:

    git pull

  2. Make change in file on your PC

  3. Stage: Tell git that you are planning to incorporate the file in your next snapshot:

    git add "your-file-to-stage"

  4. Commit: Tell git to take the snapshot:

    git commit -m "Make change x"

  5. Push: Upload the changes to GitHub:

    git push

Status, history, reverting

“What has been edited and staged?”

git status

“What has been previously committed?”

git log

“UNDO, UNDO, UNDO!”

# Undo staging
git reset yourstagedfile

# Undo last commit
git revert HEAD

☕ BREAK 2

Interactivity: embed H5P

  1. Find H5P content
  2. Click “Embed <>”
  3. Copy-paste code into qmd file
  4. Render!

Interactivity: webexercises

With the {webexercises} R package!

  1. Install + load R package

     ```{r}
 install.packages("webexercises")
 library(webexercises)
 ```

  2. Add to Quarto

     add_to_quarto()

  3. Use exercises

Publishing and archiving

Finished (a full version of) the book? Archive it!

  1. Create an ORCID
  2. Log into Zenodo (or Zenodo Sandbox)
  3. Link your Zenodo account to ORCID ánd GitHub account
  4. In Zenodo, go to Settings > GitHub, and “Flip the switch” of your to-be-archived repository.
  5. In GitHub, create a Release.
  6. Published! If needed, edit the Zenodo metadata.

Steps are outlined here with screenshots

Thanks!

Open textbooks for EduSupport @ UU